Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSBundle 

Inherits From:	NSObject

Conforms To:	NSObject (NSObject)

Declared In:	Foundation/NSBundle.h 

Class Description

A bundle is a mechanism for grouping application resources into convenient chunks. A typical (but by no means the only) application of a bundle is to group executable code together with the resources used by that executable code. A major use of bundles is to handle localization issues, as described below in ªLocalized Resourcesº.

An NSBundle is an object that corresponds to a directory (or folder in the terminology of some operating systems) where application resources are stored. The directory, in essence, ªbundlesº a set of resources used by an application, and the NSBundle object makes those resources available to the application. NSBundle is able to find requested resources in the directory and, in some cases, dynamically load executable code. The term ªbundleº is used both for the object and for the directory it represents.

Bundled resources might include such things as:

·	ImagesÐTIFF or EPS (for instance) images used by an application's user interface components

·	Sounds

·	Localized character strings

·	Executable code

·	User Interface resourcesÐfiles describing the layout of user interface objects and their relationships with other objects

Each resource within a bundle usually resides in a separate file. 

Localized Resources

If an application is to be used in more than one part of the world, its resources may need to be customized, or ªlocalizedº, for language, country, or cultural region. An application may need, for example, to have separate Japanese, English, French, Hindi, and Swedish versions of the character strings that label menu commands.

Resource files specific to a particular language are grouped together in a subdirectory of the bundle directory. The subdirectory has the name of the language (in English) followed by a ª.lprojº extension (for ªlanguage projectº). The application mentioned above, for example, would have Japanese.lproj, English.lproj, French.lproj, Hindi.lproj, and Swedish.lproj subdirectories.

Each ª.lprojº subdirectory in a bundle has the same set of files; all versions of a resource file must have the same name.

The Main Bundle

Every application is considered to have at least one bundleÐits main bundleÐthe directory where its executable file is located. If the application is organized into a file package marked by a ª.appº extension, the file package is the main bundle.

Other Bundles

An application can be organized into any number of other bundles in addition to the main bundle. For example, an application for managing PostScript printers may have a bundle full of PostScript code to be downloaded to printers.These other bundles usually reside inside the application file package, but they can be located anywhere in the file system. Each bundle directory is represented in the application by a separate NSBundle object.

By convention, bundle directories other than the main bundle end in a ª.bundleº extension.

Dynamically Loadable Classes

Any bundle directory can contain a file with executable code. For the main bundle, that file is the application executable that's loaded into memory when the application is launched. The executable in the main bundle includes the main() function and other code necessary to start up the application.

Executable files in other bundle directories hold class (and category) definitions that the Bundle object can dynamically load while the application runs. When asked, the Bundle returns class objects for the classes (and categories) stored in the file. It waits to load the file until those classes are needed.

By using a number of separate bundles, you can split an application into smaller, more manageable pieces. Each piece is loaded into memory only when the code being executed requires it, so the application can start up faster than it otherwise would. And, assuming users will rarely exercise every part of an application, the application will also consume less memory as it runs.

The file that contains dynamically loadable code must have the same name as the bundle directory, but without the ª.bundleº extension.

Since each bundle can have only one executable file, that file should be kept free of localizable content. Anything that needs to be localized should be segregated into separate resource files and stored in ª.lprojº subdirectories.

Working with Bundles

Generally, you instantiate a bundle object by sending one of the bundleForClass:, bundleWithPath:, or mainBundle methods to the NSBundle class object. mainBundle gives you the NSBundle object corresponding to the directory containing the application's executable.

Initializing an NSBundle 

- (id)initWithPath:(NSString *)path	Initializes a newly allocated NSBundle object to make it the NSBundle for the path directory.

Getting an NSBundle 

+ (NSBundle *)bundleForClass:(Class)aClass	Returns the NSBundle object that dynamically loaded aClass, or the main bundle object if aClass wasn't dynamically loaded.

+ (NSBundle *)bundleWithPath:(NSString *)path	Returns an NSBundle object that's initialized for the path directory.

+ (NSBundle *)mainBundle	Returns the NSBundle object that corresponds to the directory where the application executable is located.

Getting a Bundled Class 

- (Class)classNamed:(NSString *)className	Returns the class object for the className class, or nil if className isn't one of the classes associated with the receiver.

- (Class)principalClass	Returns the class object for the first class that's dynamically loaded by the NSBundle, or nil if the NSBundle can't dynamically load any classes.

Finding a Resource 

+ (NSString *)pathForResource:(NSString *)name	Returns the path for the resource identified by name,
ofType:(NSString *)ext		having the specified filename ext,
inDirectory:(NSString *)bundlePath		residing in bundlePath,
withVersion:(int)version		and having version number version.

- (NSString *)pathForResource:(NSString *)name	Returns the path for the resource identified by name
ofType:(NSString *)ext		having the specified filename extension ext.

Getting the Bundle Directory 

- (NSString *)bundlePath	Returns a string containing the full pathname of the receiver's bundle directory.

Stripping Symbols

+ (void)stripAfterLoading:(BOOL)flag	Sets whether symbols are stripped when modules are loaded. The default is YES. You would usually set flag to NO for debugging purposes.

Managing Localized Resources

- (NSString *)localizedStringForKey:(NSString *)key	
value:(NSString *)value	Returns a localized version of the string designated by 
table:(NSString *)tableName		key. tableName specifies the string table to search; if 
		tableName is NULL, the file Localizable.strings is used. value specifies the value to return if the key or table can't be found (or if key is NULL).

Setting the Version 

- (unsigned)bundleVersion	Returns the version last set by the setBundleVersion: method, or 0 if no version has been set.

- (void)setBundleVersion:(unsigned)version	Sets the version that the NSBundle will use when searching ª.lprojº subdirectories for resource files.